---
title: Theming
menu: Customization
order: 10
---

# Theming

Smooth UI is entirely configurable from the theme. It uses [Styled Components theming feature](https://www.styled-components.com/docs/advanced#theming) or [emotion-theming](https://emotion.sh/docs/theming) under the hood. You can customize nearly anything using the theme!

## Theme engine

Smooth UI relies on [styled-components theming](https://www.styled-components.com/docs/advanced#theming) and [emotion theming](https://emotion.sh/docs/theming) that works similarly. If you already use it in your application, it will work out of the box!

## Theme specification

Smooth UI uses [xstyled](https://www.smooth-code.com/open-source/xstyled/) that implements a powerful [theme specification](https://www.smooth-code.com/open-source/xstyled/docs/theme-specification/).

All system properties are binded to the theme, it really gives super powers!

## Use a custom theme

You can use the `ThemeProvider` provided by `styled-components` or `emotion-theming`. You must set your provider up before any Smooth UI component.

```jsx live noInline
import React from 'react'
import { ThemeProvider } from 'styled-components'
import { Button } from '@smooth-ui/core-sc'

const theme = {
  colors: {
    primary: 'blue',
  },
}

function Example() {
  return <Button>Hello world</Button>
}

render(
  <ThemeProvider theme={theme}>
    <Example />
  </ThemeProvider>,
)
```

## Default theme

Smooth UI automatically merges its default theme in components. If you want to use Smooth UI theme in your application you can import it directly from `@smooth-ui/core-sc` or `@smooth-ui/core-em`.

All theme values are [in the code](https://github.com/smooth-code/smooth-ui/tree/master/packages/shared/core/theme/common).

```jsx
import { theme } from '@smooth-ui/core-sc'
import { ThemeProvider } from 'styled-components'
import App from './App'

render(
  <ThemeProvider theme={theme}>
    <App />
  </ThemeProvider>,
)
```

## Use theme in properties

`@xstyled/system` is implemented in all components, your theme value can be used in any of them.

For example, you can define the background color of a button with a property:

```jsx live noInline
import React from 'react'
import { ThemeProvider } from 'styled-components'
import { Button } from '@smooth-ui/core-sc'

const theme = {
  colors: {
    awesomeColor: 'violet',
  },
}

function Example() {
  return <Button backgroundColor="awesomeColor">Hello world</Button>
}

render(
  <ThemeProvider theme={theme}>
    <Example />
  </ThemeProvider>,
)
```

> To learn more about system properties, see [xstyled system properties](https://www.smooth-code.com/open-source/xstyled/docs/system-props/).

## Build components with theme

`@xstyled/system` provides lot of utilities to access the theme in your components.

For example, you can use `th` to access a theme property:

```jsx
import { th } from '@xstyled/system'

const RedBox = styled.div`
  background-color: ${th.color('primary')};
`
```

> To learn more about system components, see [xstyled system utilities](https://www.smooth-code.com/open-source/xstyled/docs/system-utilities/).

## Theme reference

Smooth UI also supports theme reference, using `th` you can refer to another theme value without repeating it:

```js
// theme.js
import { th } from '@xstyled/system'

export const colors = {
  blue: '#00bdff',
  // primary is now a reference to `blue`
  primary: th.color('blue'),
}
```
